﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>Format - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The Format function formats a variable number of input values according to a format string." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Format</h1>

<p>根据格式字符串格式化一个可变数量的输入值.</p>

<pre class="Syntax">String := <span class="func">Format</span>(FormatStr <span class="optional">, Values...</span>)</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>FormatStr</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>格式字符串由原义文本和占位符组成, 其形式为 <code>{<i>Index</i>:<i><a href="#FormatSpec">Format</a></i>}</code>.</p>
    <p><em>Index</em> 是一个整数, 表示要使用的那个输入值, 其中 1 是第一个值.</p>
    <p><em>Format</em> 是一个可选的格式指定器, 如下文所述.</p>
    <p>省略索引可以使用序列中的下一个输入值(即使先前已经被使用过). 例如, <code>"{2:i} {:i}"</code> 会将第二个和第三个输入值格式化成十进制整数, 用空格隔开. 如果省略了 <em>Index</em>, 仍然必须在 <em>Format</em> 前面加上 <code>:</code>. 指定空大括号, 将使用默认格式处理下一个输入值: <code>{}</code></p>
    <p>使用 <code>{{}</code> 和 <code>{}}</code> 来包含字符串中的原义括号. 任何其他无效的占位符都会被包含在结果中.</p>
    <p>不允许在大括号中包含空格符(除非作为标志).</p>
  </dd>

  <dt>Values</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a>, <a href="../Concepts.htm#numbers">整数</a>或<a href="../Concepts.htm#numbers">浮点数</a></p>
    <p>将要格式化的输入值. 每个值都是一个独立的参数. 第一个值的索引为 1.</p>
    <p>要传递一个数组值, 可以使用<a href="../Functions.htm#VariadicCall">可变函数调用</a>:</p>
    <pre>arr := [13, 240]
MsgBox Format("{2:x}{1:02x}", arr*)</pre>
  </dd>

</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
<p>该函数返回指定字符串的格式化版本.</p>

<h2 id="FormatSpec">格式指定器</h2>
<p>每个格式指定器可以按顺序包含以下几个部分(不含空格):</p>
<pre class="Syntax">Flags Width .Precision ULT Type</pre>
<p><strong>Flags</strong>: 从下面的<a href="#Flags">标志表</a>中选择零个或多个标志来影响输出的对齐方式和前缀.</p>
<p><strong>Width</strong>: 十进制整数, 控制格式化值的最小宽度, 以字符为单位. 默认情况下, 值是右对齐的, 使用空格进行填充. 这可以通过使用 <code>-</code>(左对齐) 和 <code class="no-highlight">0</code>(前缀 0) 标志来覆盖.</p>
<p><strong>.Precision</strong>: 十进制整数, 控制要输出的字符串, 小数位数或有效数字的最大位数, 取决于输出类型. 输出类型(Type) 的最前面必须是小数点. 指定精度可能会导致输出值被截断(或四舍五入) 或补全的方式. 输出类型以及每种类型受到精度值的影响如下(有关不同输出类型的解释, 参见下表):</p>
<ul>
  <li><code>f</code>, <code>e</code>, <code>E</code>: <em>Precision</em> 指定小数点后的位数. 默认值为 6.</li>
  <li><code>g</code>, <code>G</code>: <em>Precision</em> 指定最大的有效数字数. 默认值为 6.</li>
  <li><code>s</code>: <em>Precision</em> 指定要打印的最大字符数. 超过这个数字的字符不会被打印.</li>
  <li>对于整数类型(<code>d</code>, <code>i</code>, <code>u</code>, <code>x</code>, <code>X</code>, <code>o</code>), <em>Precision</em> 的作用类似于前缀为 <code class="no-highlight">0</code> 默认值为 1 的 <em>Width</em>.</li>
</ul>
<p id="ULT"><b>ULT</b>: 指定应用于字符串值的大小写转换 -- <b>U</b>(大写), <b>L</b>(小写) 或 <b>T</b>(标题). 仅对 <code>s</code> 类型有效. 例如 <code>{:U}</code> 或 <code>{:.20Ts}</code>. 也支持小写字母 <code>l</code> 和 <code>t</code>, 但 <code>u</code> 被保留给无符号整数.</p>
<p><strong>Type</strong>: 下面<a href="#Types">类型表</a>中一个指示输入值将被如何解析的字符. 如果省略, 默认为 <code>s</code>.</p>

<h2 id="Flags">Flags</h2>
<table class="info">
  <tr><th style="min-width:5em">标志</th><th>含义</th></tr>
  <tr>
    <td><code>-</code></td>
    <td>
      <p>在给定位宽下使结果左对齐(不足位宽的右侧部分补以空格). 例如, <code>Format("{:-10}", 1)</code> 返回 <code class="no-highlight" style="white-space: pre">1         </code>.</p>
      <p>如果省略, 结果将在给定的位宽内右对齐.</p>
    </td>
  </tr>
  <tr>
    <td><code>+</code></td>
    <td>
      <p>如果输出值是带符号的类型, 则使用符号(+ 或 -) 作为前缀. 例如, <code>Format("{:+d}", 1)</code> 返回 <code class="no-highlight">+1</code>.</p>
      <p>如果省略, 仅在输出值是负数时显示符号(-).</p>
    </td>
  </tr>
  <tr>
    <td><code class="no-highlight">0</code></td>
   <td>
      <p>如果 <em>width</em> 以 0 为前缀, 前导 0 将被添加直至最小宽度. 例如, <code>Format("{:010}", 1)</code> 返回 <code class="no-highlight">0000000001</code>. 若同时使用 <code class="no-highlight">0</code> 和 <code>-</code>, 则前者将被忽略. 如果 0 被指定为整数格式(i, u, x, X, o, d) 且同时带有精度指示 - 例如, <code class="no-highlight">{:04.d}</code> - 此时的 0 会被忽略.</p>
      <p>如果省略, 不填充.</p>
    </td>
  </tr>
  <tr>
    <td><code>&nbsp;</code>(空格)</td>
    <td>
      <p>当输出值有符号且为正数时, 以 <em>单个</em> 空格为前缀来修饰. 如果空格 <code>&nbsp;</code> 和 <code>+</code> 同时出现时, 空格将被忽略. 例如, <code>Format("{:&nbsp;05d}", 1)</code> 返回 <code class="no-highlight" style="white-space: pre"> 0001</code>.</p>
      <p>如果省略, 无空格.</p>
    </td>
  </tr>
  <tr>
    <td><code>#</code></td>
    <td>
      <p>当 # 和 o, x 或 X 格式一起使用时, 此标志使用 <code class="no-highlight">0</code>, <code class="no-highlight">0x</code> 或 <code class="no-highlight">0X</code> 的形式分别修饰任意非零的输出值. 例如, <code>Format("{:#x}", 1)</code> 返回 <code class="no-highlight">0x1</code>.</p>
      <p>当 # 和 e, E, f, a, A 格式一起使用时, 此标志强制使输出值包含小数点. 例如, <code>Format("{:#.0f}", 1)</code> 返回 <code class="no-highlight">1.</code>.</p>
      <p>当 # 和 g 或 G 一起使用时, 此标志强制使输出值包含小数点并保留末尾的 0.</p>
      <p>当 # 和 c, d, i, u 或 s 格式一起使用时会被忽略.</p>
    </td>
    <td></td>
  </tr>
</table>
<h2 id="Types">Types</h2>
<table class="info">
  <tr><th style="min-width:5em" abbr="Type Char">
类型字符</th><th style="min-width:5em">参数</th><th abbr="Out format">输出格式</th></tr>
  <tr>
    <td><code>d</code> 或 <code>i</code></td>
    <td>整数</td>
    <td>有符号整数. 例如, <code>Format("{:d}", 1.23)</code> 返回 <code class="no-highlight">1</code>.</td>
  </tr>
  <tr>
    <td><code>u</code></td>
    <td>整数</td>
    <td>无符号整数.</td>
  </tr>
  <tr>
    <td><code>x</code> 或 <code>X</code></td>
    <td>整数</td>
    <td>无符号十六进制整数; 由 <code>x</code> 的大小写形式决定输出值是 "abcdef" 还是 "ABCDEF" 的形式, 仅当使用了 <code>#</code> 标志时, <code class="no-highlight">0x</code> 前缀才会包含到输出值中, 如 <code>{:#x}</code>. 要总是包含前缀, 请使用 <code class="no-highlight">0x{:x}</code> 或类似的. 例如, <code>Format("{:X}", 255)</code> 返回 <code>FF</code>.</td>
  </tr>
  <tr>
    <td><code>o</code></td>
    <td>整数</td>
    <td>无符号八进制整数. 例如, <code>Format("{:o}", 255)</code> 返回 <code class="no-highlight">377</code>.</td>
  </tr>
  <tr>
    <td><code>f</code></td>
    <td>浮点数</td>
    <td>形如 [ - ]<em>dddd</em>.<em>dddd</em> 的有符号数值, <em>dddd</em> 可以是一位或多位十进制数字. 小数点前的数字位数取决于整数部分的大小, 小数点后的数字位数取决于需求的精度. 例如, <code>Format("{:.2f}", 1)</code> 返回 <code class="no-highlight">1.00</code>.</td>
  </tr>
  <tr>
    <td><code>e</code></td>
    <td>浮点数</td>
    <td>形如 [ - ]<em>d.dddd</em> e [<em>符号</em>]<em>dd[d]</em> 的有符号值, 这里的 <em>d</em> 是一位数字, <em>dddd</em> 是一位或多位数字, <em>dd[d]</em> 是两或三位数字, 取决于输出格式的定义和指数的大小, 这里的 <em>符号</em> 是 + 或 -. 例如, <code>Format("{:e}", 255)</code> 返回 <code class="no-highlight">2.550000e+002</code>.</td>
  </tr>
  <tr>
    <td><code>E</code></td>
    <td>浮点数</td>
    <td>等同于 <code>e</code> 格式, 但结果中指数部分显示的是 E 而不是 e.</td>
  </tr>
  <tr>
    <td><code>g</code></td>
    <td>浮点数</td>
    <td>以 <code>f</code> 或 <code>e</code> 格式显示带符号的值, 以给定值和精度更紧凑的为准. <code>e</code> 格式只在值的指数小于 -4 或大于或等于 <em>precision</em> 参数时使用. 尾部的零被截断, 小数点只在后面有一个或多个数字时才会出现.</td>
  </tr>
  <tr>
    <td><code>G</code></td>
    <td>浮点数</td>
    <td>等同于 <code>g</code> 格式, 但引入指数时的 e 将被 E 代替(在适当的地方).</td>
  </tr>
  <tr>
    <td><code>a</code></td>
    <td>浮点数</td>
    <td>形如 [?]0x<em>h.hhhh</em> <strong>p</strong>&plusmn;<em>dd</em> 的有符号十六进制双精度浮点值, 其中 <em>h.hhhh</em> 的小数部分是十六进制数值(使用小写字母), 而 <em>dd</em> 是代表指数的一个或多个数字, 精度指定了小数点后的位数.</td>
  </tr>
  <tr>
    <td><code>A</code></td>
    <td>浮点数</td>
    <td>等同于 <code>a</code> 格式, 但当引入指数时使用 P, 而不是 p.</td>
  </tr>
  <tr>
    <td><code>p</code></td>
    <td>整数</td>
    <td>将参数显示为十六进制的内存地址. 例如, <code>Format("{:p}", 255)</code> 返回 <code class="no-highlight">000000FF</code>.</td>
  </tr>
  <tr>
    <td><code>s</code></td>
    <td>字符串</td>
    <td>输出字符串. 如果输入值是数值, 该输入值会在 <em>Width</em> 和 <em>Precision</em> 生效前, 自动转换为字符串.</td>
  </tr>
  <tr>
    <td><code>c</code></td>
    <td>字符编码</td>
    <td>按照编码顺序输出一个单字符, 类似于 <code><a href="Chr.htm">Chr</a>(n)</code>. 如果输入值不在预期范围内将被回转. 例如, <code>Format("{:c}", 116)</code> 返回 <code>t</code>.</td>
  </tr>
</table>

<h2 id="Remarks">备注</h2>
<p>不同于 <a href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions">printf</a>, 不支持大小指定符. 所有的整数和浮点数输入值都是 64 位的.</p>

<h2 id="Related">相关</h2>
<p><a href="FormatTime.htm">FormatTime</a></p>

<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a class="ex_number" href="#ExBasic"></a> 演示不同的用法.</p>
<pre>
s := ""
<em>; 简单替换</em>
s .= Format("{2}, {1}!`r`n", "World", "Hello")
<em>; 填充空格</em>
s .= Format("|{:-10}|`r`n|{:10}|`r`n", "Left", "Right")
<em>; 十六进制</em>
s .= Format("{1:#x} {2:X} 0x{3:x}`r`n", 3735928559, 195948557, 0)
<em>; 浮点数</em>
s .= Format("{1:0.3f} {1:.10f}", 4*ATan(1))

ListVars  <em>; 用 AutoHotkey 的主窗口显示等宽文本.</em>
WinWaitActive "ahk_class AutoHotkey"
ControlSetText(s, "Edit1")
WinWaitClose
</pre>
</div>

</body>
</html>